CSV 디렉터리 동기화

메뉴 경로 : 설정 > 인바운드 프로비저닝 > CSV 디렉터리 동기화

개요

FTP 또는 SFTP 서버에 업로드된 CSV 파일을 주기적으로 감시하여 사용자 및 그룹 정보를 Security365 관리센터로 자동 동기화하는 기능입니다. 별도의 외부 디렉터리 서버(HR 시스템 등)에서 생성되는 CSV 파일을 연동할 때 활용합니다.

동작 흐름:

단계	내용
1	FTP/SFTP 서버에 접속
2	지정된 경로의 CSV 파일 다운로드
3	이전 동기화 대비 파일 변경 여부 확인
4	CSV 데이터 변환 및 유효성 검증
5	관리센터 사용자/그룹 정보 반영

참고: 하나의 인바운드 프로비저닝 방식만 활성화할 수 있습니다. CSV 디렉터리 동기화를 활성화하면 다른 방식(SCI Server, Microsoft365, 로컬 Active Directory)은 비활성 상태가 됩니다.

참고: 파일 내용이 변경되지 않은 경우, 동기화를 건너뜁니다. 이는 불필요한 처리를 방지하는 정상 동작입니다.

화면 구성

설정 전 : CSV 디렉터리 동기화 카드에 "설정 후 사용할 수 있습니다." 안내가 표시됩니다.

설정 완료 후 : 카드에 다음 정보가 표시됩니다.

정보	설명
연결 방식 및 서버 정보	접속 방식(SFTP/FTP), 호스트 주소, 포트, 접속 ID
마지막 동기화 일시 및 결과	최근 동기화 실행 시각과 성공/실패 여부
동기화 주기	자동 동기화 설정 시각
[수정] 버튼	설정 변경
[수동 동기화] 버튼	즉시 동기화 실행

설정 방법 (4단계)

[1단계] 서버 연결

FTP/SFTP 서버 접속 정보를 입력합니다.

항목	설명
접속 방식 (프로토콜)	FTP 또는 SFTP 선택
호스트(서버 주소)	서버 주소 (IP 또는 도메인)
포트	접속 포트 번호
접속 ID	서버 계정 ID
접속 비밀번호	서버 계정 비밀번호

접속 방식 선택 기준:

방식	기본 포트	설명	권장 상황
SFTP	22	SSH 기반 암호화 전송	보안이 필요한 환경 (권장)
FTP	21	비암호화 전송	내부 네트워크 등 보안 요건이 낮은 환경

설정 후 [연동 테스트] 버튼을 클릭하여 서버 연결 상태를 확인하세요.

주의: 저장 전 연동 테스트를 반드시 실행하여 연결을 확인하세요.

참고: 비밀번호는 암호화되어 저장되며, 설정 화면에서 평문으로 노출되지 않습니다.

버튼: 취소 | 임시 저장 | 다음

[2단계] 사용자 설정

사용자 CSV 파일의 감시 방식과 데이터 변환 규칙을 설정합니다.

감시 경로

감시 모드

모드	설명
단일 파일	지정한 경로의 파일을 감시합니다.
디렉터리	지정한 경로에서 파일 중 가장 최신 파일을 감시합니다.

디렉터리 모드 선택 시 - 최신 파일 판단 기준

기준	설명
수정일 기준	가장 최근에 수정된 파일을 최신 파일로 판단
파일명 기준	파일명에 포함된 날짜를 파싱하여 가장 최신 날짜의 파일 선택

지원 날짜 포맷 (파일명 기준 선택 시):

포맷	파일명 예시
yyyyMMdd	`users_20260101.csv`
yyyy-MM-dd	`users_2026-01-01.csv`
yy-MM-dd	`users_26-01-01.csv`
yyMMdd	`users_260101.csv`

참고: 파일명이 #으로 시작하는 파일은 주석으로 처리되어 동기화 대상에서 제외됩니다.

경로 및 파일 패턴

항목	설명	예시
경로	서버 내 파일 또는 디렉터리 경로	`data/csv/users/`
파일 패턴	감시할 파일명 패턴 (와일드카드 `*` 지원)	`users_*.csv`

동기화 옵션

항목	옵션	설명
CSV 미포함 항목 처리	유지	CSV에 없는 기존 사용자를 그대로 유지
	비활성화	CSV에 없는 기존 사용자를 비활성화 처리
검증 오류 시 동기화 중단	사용	검증 오류 발생 시 전체 동기화를 중단
	사용 안함	오류 레코드는 건너뛰고 나머지 데이터를 반영

주의: 비활성화 선택 시, CSV 파일에 포함되지 않은 기존 사용자가 모두 비활성화됩니다. 파일 내용을 반드시 사전에 확인하세요.

CSV 컨버팅 설정

CSV 파일 형식과 필드 매핑 규칙을 설정합니다.

입력 CSV 구분자

옵션	구분자 문자
콤마	`,`
파이프	`\|`
탭	(탭 문자)

필드 매핑 방식

방식	설명
헤더 기반	CSV 첫 행(헤더)의 컬럼명으로 매핑
인덱스 기반	컬럼 순서(0부터 시작)로 매핑

표준 필드 목록 (사용자)

표준 필드	필수 여부	설명
USER_ID	필수	사용자 아이디 (이메일 형식 권장)
USER_NAME	필수	사용자 이름
EMAIL	선택	이메일 주소
GROUP_ID_LIST	선택	소속 그룹 ID (여러 그룹은 콤마로 구분)
ACTIVE_STATUS	선택	활성화 여부

ACTIVE_STATUS 인식 값:

인식 값	처리 결과
`ACTIVE`, `Y`, `1`, `true` (대소문자 무관)	활성 사용자로 처리
그 외 모든 값	비활성 사용자로 처리

주의: ACTIVE_STATUS 컬럼이 잘못 매핑되거나 인식할 수 없는 값이 입력된 경우, 전체 사용자가 비활성화될 수 있습니다. 설정 변경 후 반드시 소규모 테스트를 먼저 진행하세요.

레코드 필터링 (선택)

특정 조건에 맞는 레코드만 동기화 대상으로 포함하거나 제외할 수 있습니다.

와일드카드(*) 패턴을 지원합니다.

기본 이메일 도메인 (선택)

사용자 아이디가 이메일 형식(@ 포함)이 아닌 경우, 설정한 도메인을 자동으로 추가하여 이메일 형식으로 변환합니다.

설정 예시	변환 전	변환 후
도메인: `company.com`	`hong123`	`hong123@company.com`

버튼: 취소 | 임시 저장 | 이전 | 다음

[3단계] 그룹 설정

그룹 CSV 파일의 감시 방식과 데이터 변환 규칙을 설정합니다. 구성은 사용자 설정 탭과 동일하며, 다음과 같은 차이가 있습니다.

동기화 옵션 (그룹)

항목	옵션	설명
CSV 미포함 항목 처리	유지	CSV에 없는 기존 그룹을 그대로 유지
	삭제	CSV에 없는 기존 그룹을 삭제

참고: 그룹 탭에는 검증 오류 시 동기화 중단 토글과 기본 이메일 도메인 항목이 없습니다.

항목	사용자 설정	그룹 설정
CSV 미포함 항목 처리 옵션	유지 / 비활성화	유지 / 삭제
검증 오류 시 동기화 중단	있음 (선택 가능)	없음 (오류 시 항상 전체 중단)
기본 이메일 도메인	있음	없음

표준 필드 목록 (그룹)

표준 필드	필수 여부	설명
GROUP_ID	필수	그룹 고유 ID
GROUP_NAME	필수	그룹 이름
DESCRIPTION	선택	그룹 설명
PARENT_GROUP_ID	선택	상위 그룹 ID (계층 구조 구성 시 사용)

주의: 그룹 동기화 중 오류가 발생하면 부분 반영 없이 전체 동기화가 중단됩니다. 그룹 CSV 파일의 데이터 정합성을 사전에 충분히 검토하세요.

참고: 사용자 설정과 그룹 설정 중 최소 한 쪽은 반드시 필드 매핑을 완료해야 저장할 수 있습니다.

버튼: 취소 | 임시 저장 | 이전 | 다음

[4단계] 동기화 설정

자동 동기화 주기 및 백업 옵션을 설정합니다.

항목	설명
자동 동기화	사용 / 사용 안함 선택
동기화 주기	자동 동기화 사용 시, 매일 실행할 시각(시/분) 설정
동기화 전 백업	사용 시, 동기화 실행 전 현재 사용자/그룹 데이터를 자동으로 백업

주의: 동기화 전 백업이 활성화된 경우, 백업 실패 시 동기화가 진행되지 않습니다.

참고: 모든 실행 시각은 KST(한국 표준시) 기준입니다.

버튼: 취소 | 이전 | 저장

수동 동기화

설정 저장 후 인바운드 프로비저닝 목록 화면의 CSV 디렉터리 동기화 카드에서 [수동 동기화] 버튼을 클릭하면 즉시 동기화가 실행됩니다.

동기화 완료 후 성공/실패 여부와 완료 시간이 표시됩니다.

주의: 동기화 진행 중에는 중복 실행이 불가합니다. 이전 동기화가 완료된 후 다시 실행하세요.

동기화 결과 확인

설정 완료 후 카드에서 마지막 동기화 결과를 확인할 수 있습니다.

마지막 동기화 상태 종류:

상태	설명
성공	파일 감시 및 데이터 반영 완료
변경 없음	이전 동기화 대비 파일 내용 변경 없음 (정상 동작)
연결 실패	FTP/SFTP 서버 접속 불가
파일 없음	지정된 경로에 파일이 존재하지 않음
실패	데이터 변환, 검증, 또는 반영 과정에서 오류 발생

[마지막 동기화 정보] 링크를 클릭하면 슬라이드 패널("CSV 디렉터리의 마지막 동기화 정보")이 열립니다.

항목	표시 내용
그룹 동기화	상태, 감시 경로, 마지막 동기화 일시
사용자 동기화	상태, 감시 경로, 마지막 동기화 일시

오류 대처

오류 유형	주요 증상	조치 방법
연결 오류	상태: 연결 실패	서버 주소·포트·계정 정보 확인 / 방화벽 포트 개방 여부 확인
파일 오류	상태: 파일 없음	지정된 경로 및 파일 패턴 확인 / 파일이 서버에 업로드되어 있는지 확인
변환 오류	상태: 실패	CSV 구분자 설정 확인 / 필드 매핑 설정 확인 / CSV 파일 인코딩(UTF-8) 확인
검증 오류	상태: 실패	필수 필드(USER_ID, USER_NAME / GROUP_ID, GROUP_NAME) 누락 여부 확인
반영 오류	상태: 실패	동기화 로그에서 오류 상세 내용 확인 후 담당팀 문의
백업 실패	동기화 미실행	동기화 전 백업 설정 및 백업 저장 공간 확인

주의사항

사용자 설정과 그룹 설정 중 최소 한 쪽은 반드시 필드 매핑을 완료해야 합니다. 양쪽 모두 미설정 상태로는 저장되지 않습니다.
ACTIVE_STATUS 필드 매핑이 잘못된 경우, 전체 사용자가 비활성화될 수 있습니다. 설정 변경 후 반드시 소규모 테스트를 먼저 진행하세요.
그룹 동기화 오류 발생 시, 부분 반영 없이 전체 동기화가 중단됩니다.
파일명이 #으로 시작하는 파일은 주석으로 처리되어 동기화 대상에서 제외됩니다.
파일 내용이 변경되지 않으면 동기화를 건너뜁니다. 이는 정상 동작입니다.
동기화 전 백업 옵션 활성화 시, 백업 실패가 발생하면 동기화도 중단됩니다.
모든 실행 시각은 KST(한국 표준시) 기준입니다.
동기화된 사용자/그룹 정보를 관리센터에서 직접 수정해도, 다음 동기화 실행 시 CSV 파일 기준으로 덮어씌워집니다. 영구적인 변경이 필요하다면 원본 CSV 파일 또는 소스 시스템에서 먼저 수정하세요.
하나의 인바운드 프로비저닝 방식만 활성화할 수 있으며, 다른 방식이 이미 활성화된 경우 전환 후 사용해야 합니다.

목차​

개요​

화면 구성​

설정 방법 (4단계)​

[1단계] 서버 연결​

[2단계] 사용자 설정​

감시 경로​

동기화 옵션​

CSV 컨버팅 설정​

[3단계] 그룹 설정​

동기화 옵션 (그룹)​

[4단계] 동기화 설정​

수동 동기화​

동기화 결과 확인​

오류 대처​

주의사항​

목차

개요